/**
 * 
 */
package org.stars.util.diagnostic;

import java.io.Serializable;

/**
 * <p>
 * Interfaccia per la gestione della visualizzazione mediante debug delle
 * informazioni relative allo stack trace durante l'esecuzione delle query.
 * </p>
 * <p>
 * Questa interfaccia viene utilizzata durante la normale esecuzione
 * delle query per definire quali elementi dello stack visualizzare
 * nel log del dao. 
 * </p>
 * <p>
 * Il funzionamento è presto spiegato: a fronte di un array di stack element,
 * ci si posiziona sull'elemento con indice uguale a lowerBoundInex e
 * si inizia a vedere mediante il metodo canBeginDisplay se l'elemento in question
 * può essere visualizzato. Una volta ottenuto esito positivo, viene utilizzato il
 * metodo diplay per visualizzare tutti gli elementi che si desiderano visualizzare.
 * L'interazione procede fino a quando non si raggiunge il limite superiore
 * degli elementi che si desidera visualizzare (getUpperBoundIndex) o 
 * il metodo canStopDiplay restituisce true. 
 * </p>
 * <p>
 * Si ricorda che per visualizzare tale elemento
 * </p>
 * 
 * @author Francesco Benincasa (908099)
 * 
 */
public interface StackTraceDiagnosticHandler extends Serializable {
	
	/**
	 * Verifica se la diagnostica è abilitata o meno.
	 * 
	 * @return
	 * 		<code>true</code> se si deve visualizzare lo stack trace nel log,
	 * 		<code>false</code> altrimenti.
	 */
	public boolean isEnabled();
	
	/**
	 * Imposta il trace dello stack.
	 * @param value
	 */
	public void setEnabled(boolean value);
	
	/**
	 * setter loweBoundIndex.
	 * Limite inferiore degli indici per
	 * l'array degli stack elementi.
	 * 
	 * @param lowerIndex
	 * 			indice più piccolo che si può visualizzare.
	 * 		
	 */
	public void setLowerBoundIndex(int lowerIndex);

	/**
	 * getter lowerBoundIndex.
	 * Limite inferiore degli indici dell'array
	 * dello stack di elementi.
	 * 
	 * @return
	 * 		indice più piccolo che si può visualizzare.
	 */
	public int getLowerBoundIndex();

	/**
	 * setter upperBoundIndex.
	 * Limite inferiore degli indici dell'array
	 * dello stack di elementi.
	 * 
	 * @param upperLimit
	 * 		indice più grande che si può visualizzare.
	 */
	public void setUpperBoundIndex(int upperLimit);

	/**
	 * getter upperBoundIndex.
	 * Limite inferiore degli indici dell'array
	 * dello stack di elementi.
	 * 
	 * @return
	 * 		indice più grande che si può visualizzare.
	 */
	public int getUpperBoundIndex();

	/**
	 * Metodo per determinare se a fronte dell'elemento dello
	 * stack passato come argomento del metodo si può iniziare
	 * a visualizzare gli elementi dello stack trace.
	 * 
	 * @param index
	 * 			indice dello stack attualmente analizzato
	 * @param element
	 * 			elemento dello stack attualmente analizzato
	 * @return
	 * 		<code>true</code> se si può iniziare a visualizzare gli
	 * 		elementi dello stack
	 */
	public boolean canBeginDisplay(int index, StackTraceElement element);

	/**
	 * Dato un elemento dello stack da visualizzare, restituisce la
	 * stringa da visualizzare nel debug
	 * 
	 * @param index
	 * 			indice dello stack attualmente analizzato
	 * @param element
	 * 			elemento dello stack attualmente analizzato
	 * @return
	 * 			stringa da visualizzare
	 */
	public String getStringToDisplay(int index, StackTraceElement element);

	/**
	 * Metodo per determinare se a fronte dell'elemento dello
	 * stack passato come argomento del metodo si può fermare
	 * la visualizzazione degli elementi dello stack trace.
	 * 
	 * @param index
	 * 			indice dello stack attualmente analizzato
	 * @param element
	 * 			elemento dello stack attualmente analizzato
	 * @return
	 * 		<code>true</code> se si può iniziare a visualizzare gli
	 * 		elementi dello stack
	 */
	public boolean canStopDisplay(int index, StackTraceElement element);
}
